home *** CD-ROM | disk | FTP | other *** search
/ Software Vault: The Gold Collection / Software Vault - The Gold Collection (American Databankers) (1993).ISO / cdr49 / 115_01.zip / MODULE.DOC < prev    next >
Text File  |  1993-06-01  |  5KB  |  159 lines
  1. .cm screen editor:  module documentation
  2. .cm source:  module.doc
  3. .cm
  4. .he 'module.doc''March 12, 1981'
  5. .fo ''-#-''
  6.  
  7. .ul
  8. organization into modules
  9.  
  10.    The screen editor is organized into separate
  11. modules (or "abstract data types" if you want to
  12. use fancy words).
  13. If you understand how and why the program is 
  14. organized into these modules then you understand
  15. the basics of the program.
  16. If you don't, you don't understand the program.
  17. It's that simple.
  18.  
  19.    I followed three rules religiously while writing
  20. this program.
  21. If you modify this program I want you to follow
  22. them too.
  23. Here they are:
  24.  
  25. Rule 1:
  26.  
  27.    No program shall use any data contained in another
  28. module.
  29. That is, all access to data contained in
  30. a module must be via the "access routines" of
  31. that module.
  32.  
  33. Rule 2:
  34.  
  35.    No access routine may reveal to the outside world the
  36. internal representation of data inside the
  37. access routine's own module.
  38. In other words, the access routines of a module only
  39. indicate
  40. .ul
  41. what
  42. the module does, not
  43. .ul
  44. how
  45. the module does it.
  46.  
  47. Rule 3:
  48.  
  49.    Every significant (i.e., relatively complex)
  50. data structure shall reside in one and only one
  51. module.
  52.  
  53.    Each module, then, is responsible for hiding
  54. the details about some important data structure.
  55. To be more precise, each module hides how the
  56. module's internal data is represented.
  57. The idea is that the organization of the data
  58. may be changed inside a module without the
  59. programs that use the module knowing that anything
  60. has changed.
  61.  
  62.    Modules not only contain data;
  63. just as importantly they also contain access routines
  64. by which procedures outside the module may use or
  65. change the data.
  66. The access routines are to be considered part of
  67. the module's data structure.
  68. I will sometimes speak of the "associated operations"
  69. of a module or data structure.
  70. By that I will mean the externally visible access
  71. routines of the module.
  72.  
  73.    Since modules (or data structures) have associated
  74. operations, the concept of data structure widens to
  75. include dynamic devices such as disk drives,
  76. video screens, and operating systems!
  77. Indeed, I use modules to shield
  78. the rest of the program from the details of such
  79. devices.
  80.  
  81.    Rule 1 says that programs outside a module
  82. can only use or change the data inside the module
  83. by calling the "access routines" of the module".
  84. No diddling with other module's data is allowed.
  85. Period.
  86.  
  87.    Rule 2 says that these access routines are
  88. .ul
  89. functions
  90. of the data.
  91. That is, the values returned and the effects 
  92. produced by the access routines are independent
  93. of how the data of the module is represented.
  94. Rule 2 should
  95. .ul
  96. eliminate
  97. data dependencies between
  98. modules.
  99.  
  100.    Rule 2 doesn't quite say enough.
  101. Not only must access routines hide their module's
  102. representation of data, access routines must
  103. provide one and only one function to the outside
  104. world.
  105. In other words, there must not be complex links
  106. between access functions in the
  107. .ul
  108. same
  109. module.
  110. (By definition there are no links between access
  111. functions of
  112. .ul
  113. different
  114. modules.)
  115. Especially to be avoided are requirements like:
  116. access functions A, B, and C must always be
  117. called in that order.
  118.  
  119.    Rule 3 says that
  120. .ul
  121. all
  122. important data structures
  123. are protected from meddling from outside sources,
  124. or conversely, no program needs to know
  125. (or can know) about details of data structures
  126. outside it's own module.
  127.  
  128.    A corollary of these rules is that there are
  129. .ul
  130. no
  131. global data structures.
  132. Indeed, there is seldom if ever a need for any
  133. global variables at all.
  134. Variables may be shared by more than one routine,
  135. but all such routines will reside in the same
  136. module.
  137.  
  138.    Not every routine needs to be a member
  139. of a module.
  140. Those routines that are not a member of any
  141. module know the details of none of the
  142. important data structures of the program.
  143.  
  144.    There is a certain optimal complexity for
  145. the data structure enclosed by a module.
  146. If the structure is too complex then too many
  147. routines (all of them inside the module!)
  148. know details of the data structure.
  149. On the other hand, if a structure is too simple
  150. then wrapping a module around it increases the
  151. overall conceptual overhead of the program.
  152. Note that a single variable may often suitable
  153. as the data structure of a module if the
  154. associated operations of the module are
  155. sufficiently complex.
  156. For example, the program counter in an assembler
  157. may make an ideal abstract data type.
  158.  
  159.